devfandomcom-20200223-history
Colors
This is a library for handling colors in the Fandom environment. This library serves two purposes: # It provides a list of the most important colors on the current page, so you can easily adapt your addon's appearance to the host wiki's color scheme. # And it provides a bunch of functions for manipulating colors, so you can build your own color scheme on top of the host wiki's color scheme Note: This library is meant to be used by JavaScript developers. If you're not writing a script, this library won't be of any use to you. You may want to check out to find out more information about colors. Colors Applying the colors The easiest way to use the above colors is to write regular CSS but use pseudo-colors instead of regular ones: a { color: $link; } Add all of these rules to a string and then pass it to dev.colors.css(). dev.colors.css() will replace all pseudo-values and append the stylesheet to the document head: Example 1: dev.colors.css( 'a { color: $link; }' ); You can use an optional second parameter to add pseudo-values of your own. Note that you need to prefix the name of your own values with a $ sign: Example 2: dev.colors.css( 'a { color: $link; background: $myBackGround; }', { myBackGround: 'black' }); Brightness and Darkness A key part of designing for the various color schemes across Fandom is to determine whether the scheme is bright or dark. dev.colors offers a method for that, but more importantly: It will add two classes to the body tag: # .menu-dark or .menu-bright – depending on whether the background of menu and buttons is dark or bright # .page-dark or .page-bright – depending on whether the background of the article area is dark or bright Manipulating Colors To manipulate color you first need to create a color object. dev.colors provides three Factories: // parse allows you to create a color object from a string: var red = dev.colors.parse("#FF0000"); var red = dev.colors.parse("#F00"); var red = dev.colors.parse("rgb(255, 0, 0)"); var red = dev.colors.parse("red"); // the values of dev.colors.wikia are strings too: var body = dev.colors.parse(dev.colors.wikia.body); // fromRgb allows you to set the RGB values numerically: // (values must be between 0 and 255) var red = dev.colors.fromRgb(255, 0, 0); // fromHsl allows you to use the HSL color model: // (values must be between 0 and 1) var red = dev.colors.fromHsl(0, 1, 1); Once you have a color object you can manipulate it: // lighten red by 20 percent: var lightRed = red.lighten(20); // desaturate red by 20 percent: var paleRed = red.saturate(-20); // rotate the hue by 180 degrees to // get the complementary color: var cyan = red.rotate(180); // mix two colors: var orange = red.mix('yellow'); Negating colors dev.colors has two functions for negating colors: complement() and invert(). While both are mathematically simple their effect on colors is a bit difficult to visualize: * invert() negates hue, saturation and lightness of a color because it acts on the RGB color space: rgbinverted = rgb(maxr – r, maxg – g, maxb – b) * complement() negates only the hue. Saturation and lightness remain unchanged.: hslcomplemented = hsl(maxh – h, s, l) The most obvious consequence is that complement() only affects colors. White, black and any gray tone in between remain (seemingly) unchanged. A few examples: Converting Color Objects to Strings When you've mixed and matched the colors you like, you will want to convert them back into strings so you can use them in CSS: console.log("red: " + red.hex()); // outputs: "red: #FF000" console.log("red: " + red.rgb()); // outputs: "red: rgb(255, 0, 0)" console.log("red: " + red.hsl()); // outputs: "hsl: hsl(0, 100%, 100%)" // hex format is the default: console.log("red: " + red); // outputs: "red: #FF0000" Edge Conditions The HSL color space allows for changes that have no visual effect: * If the saturation of a color is 0, a change of hue no longer has a visual effect. The color will remain a graytone * If the lightness of a color is 0, neither a change of hue nor a change of saturation will have a visual effect. The color will remain black. This library does not filter and discard values that have no effect. The following methods make use of the HSL color space: * Color.rotate * Color.hue * Color.saturate * Color.saturation * Color.lighten * Color.lightness * Color.complement Reference Methods of dev.colors dev.colors.parse | return = new Color object | throws = Error if string cannot be parsed or values are out of bounds | description = Examples: var red = dev.colors.parse('#FF0000'), green = dev.colors.parse('#0F0'), blue = dev.colors.parse('rgb(0, 0, 255)'), white = dev.colors.parse('white'), page = dev.colors.parse(dev.colors.wikia.page); }} | related = dev.colors.fromHsl and dev.colors.fromRgb }} dev.colors.fromRgb | parameter2 = | parameter3 = | return = new Color object | throws = Error if parameters aren't numbers or out of bounds | description = Example: var red = dev.colors.fromRgb(255, 0, 0); }} | related = dev.colors.parse and dev.colors.fromHsl }} dev.colors.fromHsl | parameter2 = | parameter3 = | return = new Color object | throws = Error if parameters aren't numbers or out of bounds | description = Example: var red = dev.colors.fromHsl(0, 1, 1); }} | related = dev.colors.parse and dev.colors.fromRgb }} dev.colors.css | description: … }} | usage2 = | parameter2 = | description: … }} | related = pseudo-colors }} Methods of Color Objects Color.rotate | return = new Color object | throws = Error if degree is not a number or out of bounds | description = var magenta = dev.colors.parse('lime').rotate(180); var blue = blue.rotate(360).rotate(-360); // no change! }} | related = Color.hue }} Color.saturate | return = new Color object | throws = Error if percentage is not a number or out of bounds | description = var paleBlue = dev.colors.parse('blue').saturate(-10); }} | related = Color.saturation }} Color.lighten | return = new Color object | throws = Error if percentage is not a number or out of bounds | description = var darkBlue = dev.colors.parse('blue').lighten(-10); }} | related = Color.lightness }} Color.mix | return = new Color object | throws = Error if otherColor is not a Color object or cannot be parsed | description = Mixes the two colors in equal proportion (50-50) var orange = yellow.mix('red'); }} | usage2 = | parameter2 = | return = new Color object | throws = Error if otherColor is not a Color object or cannot be parsed | description = Mixes a second color with the object's current color. The given weight value biases the proportion/dominance of the current color. Values below 50 bias against the current color, values above 50 are in favor of it. var sunYellow = yellow.mix('red', 80); }} }} Color.invert | related = Color.complement }} Color.complement | related = Color.invert }} Color.isBright | related = Color.lightness }} Color.isColor | related = Color.saturation }} Color.red | usage2 = | return = new Color object | throws = Error if value is not a number or out of bounds | description = var white = cyan.red(255); }} | related = Color.green, Color.blue and colors.fromRgb }} Color.green | usage2 = | return = new Color object | throws = Error if value is not a number or out of bounds | description = var white = magenta.green(255); }} | related = Color.red, Color.blue and colors.fromRgb }} Color.blue | usage2 = | return = new Color object | throws = Error if value is not a number or out of bounds | description = var white = yellow.blue(255); }} | related = Color.red, Color.green and colors.fromRgb }} Color.hue | usage2 = | return = new Color object | throws = Error if value is not a number or out of bounds | description = var red = cyan.hue(0); }} | related = Color.saturation, Color.lightness and colors.fromHsl }} Color.saturation | usage2 = | return = new Color object | throws = Error if value is not a number or out of bounds | description = var white = red.saturation(0); }} | related = Color.hue, Color.lightness and colors.fromHsl }} Color.lightness | usage2 = | return = new Color object | throws = Error if value is not a number or out of bounds | description = var black = red.lightness(0); }} | related = Color.hue, Color.saturation and colors.fromHsl }} Color.rgb | related = Color.hex, Color.hsl }} Color.hsl | related = Color.hex, Color.rgb }} Color.hex | related = Color.hsl, Color.rgb }} Color.toString | related = Color.hex }} __NOWYSIWYG__